# Primitives

## useNavigate

Hook that returns a function to programmatically navigate between routes.

**Type:**

```ts
useNavigate(): (href: string, options?: NavigateOptions) => void
```

**Parameters:**

- `href`: The destination path, can include query strings
- `options`: Optional configuration
  - `relative`: If `false`, navigates to the absolute path without relative base. Defaults to `true`
  - `replace`: If `true`, replaces the current history entry
  - `noScroll`: If `true`, prevents scrolling to top when navigating
  - `state`: Optional state object to pass to `history.state`, defaults to `null`

**Example:**

```jsx
function NavigationComponent() {
  const navigate = useNavigate()

  return (
    <>
      <button onClick={() => navigate('/')}>Home</button>
      <button onClick={() => navigate('/products', { relative: false })}>
        Products
      </button>
      <button onClick={() => navigate('/login', { replace: true })}>
        Login
      </button>
      <button onClick={() => navigate('/details', { noScroll: true })}>
        View Details (No Scroll)
      </button>
      <button onClick={() => navigate('/search?q=zess&page=1')}>
        Search Zess (Page 1)
      </button>
      <button onClick={() => navigate('/checkout', { state: { userId: 1 } })}>
        Proceed to Checkout
      </button>
    </>
  )
}
```

## useSearchParams

Hook that provides access to search parameters and a function to update them.

**Type:**

```ts
useSearchParams(): [SearchParams, (params: Record<string, any>, options?: SearchParamsOptions) => void]
```

**Returns:** An array containing

- `searchParams`: A reactive object with current search parameters that auto-updates when `location.search` changes or when modified via `setSearchParams`
- `setSearchParams`: A function to update search parameters
  - `params`: Search parameters to merge with existing ones. Setting a property value to `undefined`, `null` or an empty string removes that property
  - `options`: Optional configuration object
    - `replace`: Optional flag to replace the current history entry instead of pushing a new one
    - `state`: Optional state object to pass to `history.state`, defaults to `null`

**Example:**

```jsx
function ProductFilter() {
  const [searchParams, setSearchParams] = useSearchParams()
  const setCategory = (category) => setSearchParams({ category })
  const search = (keyword, searchType) => {
    setSearchParams(
      { keyword },
      {
        replace: true,
        state: { searchType },
      },
    )
  }
  const clearFilters = () => {
    setSearchParams({ category: undefined, keyword: undefined })
  }

  return (
    <div>
      <p>Current category: {searchParams.category || 'All'}</p>
      <p>Search keyword: {searchParams.keyword || 'None'}</p>
      <button onClick={() => setCategory('shoes')}>Set Category</button>
      <button onClick={() => search('sale', 'quick')}>Search with Type</button>
      <button onClick={clearFilters}>Clear Filters</button>
    </div>
  )
}
```

## useBeforeLeave

Hook that registers a listener to be called before leaving the current route. This allows you to intercept navigation attempts and potentially prevent them, for example, to warn users about unsaved changes.

**Type:**

```ts
useBeforeLeave(listener: RouteGuardListener): void
```

**Parameters:**

- `listener`: A function that will be called with a `RouteGuardEvent` object when navigation away from the current route is attempted
  - `event`: The route guard event object containing:
    - `to`: The destination path being navigated to
    - `from`: The current path being navigated from
    - `options`: Navigation options including `relative`, `replace`, and `noScroll`
    - `defaultPrevented`: Boolean indicating if the navigation has been prevented
    - `preventDefault`: Function to call to prevent the navigation
    - `retry`: Function to retry the navigation later, with an optional `force` parameter to bypass guards

**Example:**

```jsx
function FormEditor() {
  const [hasUnsavedChanges, setHasUnsavedChanges] = useSignal(false)
  useBeforeLeave((event) => {
    if (hasUnsavedChanges()) {
      const confirmed = window.confirm(
        'You have unsaved changes. Are you sure you want to leave?',
      )
      if (!confirmed) {
        event.preventDefault()
      }
    }
  })

  return (
    <div>
      <input type="text" onChange={() => setHasUnsavedChanges(true)} />
      <button onClick={() => setHasUnsavedChanges(false)}>Save</button>
    </div>
  )
}
```

## useLocation

Hook that returns a reactive `Location` object containing information about the current URL. This object automatically updates when the URL changes.

**Type:**

```ts
useLocation(): Location
```

**Returns:** A reactive `Location` object with `pathname` and other properties

- `pathname`: The path portion of the URL excluding the query string
- `search`: The query string portion of the URL
- `hash`: The hash portion of the URL including the `#` symbol
- `state`: The state object associated with the current history entry passed via `useNavigate` or `<Link>` component
- `query`: A reactive object containing all query parameters of the URL

**Example:**

```jsx
function LocationDisplay() {
  const location = useLocation()

  return (
    <div>
      <h2>Current Location Information</h2>
      <p>pathname: {location.pathname}</p>
      <p>search: {location.search}</p>
      <p>hash: {location.hash}</p>
      <p>state: {JSON.stringify(location.state)}</p>
      <p>query: {JSON.stringify(location.query)}</p>
    </div>
  )
}
```
